'.\" t
.TH "appconf.xml" "1M" "Jun 30, 2005" "1\&.0\&.0"
.SH NAME
appconf.xml \- Linuxha.net Cluster Application Config File

.SH SYNOPSIS
Definition of Linuxha.net Cluster Application Config File

A sample configuration file may look similar to the following:

.TS
l.
<?xml version="1.0"?>
<appconf>
    <global>
        <version>0.1</version>
        <name>apache</name>
        <takeover>normal</takeover>
        <preferred_node>LEAST_CPU_LOAD</preferred_node>
    </global>
    <networks>
        <network net="production" 
            ip="172.16.235.200"
            netmask="255.255.255.0"/>
        <network net="private" ip="175.100.10.22"/>
    </networks>
    <vg>
        <name>app01vg</name>
        <type>filesystems</type>
    </vg>
    <application>
        <startscript>/apache/admin/scripts/startapp</startscript>
        <stopscript>/apache/admin/scripts/shutdown</stopscript>
        <maxstoptime>10</maxstoptime>
        <maxstarttime>20</maxstarttime>
    </application>
</appconf>
.TE

.SH THE GLOBAL SECTION
The globals section defines general characteristics for the application. Unless
specified below each entry should be considered mandatory.

.TS
center box expand ;
l l.
Variable	Purpose
_
name	The name of the application - should be a single word
	consisting of alpha numerics and underscores. A typical
	value might be "apache".
version	The version of the configuration file. Until version
	1.0 of Linuxha this should be left as "0.1".
takeover	The type of fail-over that should be performed. This
	can be either "normal" or "force". The "force" option
	should be used after careful consideration - since it
	allows the cluster to start the application with stale
	data in some circumstances.
preferred_node	This optional parameter can be used to indicate
	which node should be used when applications are started
	via the \fIclrunapp(1M)\fP or \fIclform(1M)\fP commands.
	The value given can be either a particular node name
	or one of two special constants; "LEAST_APP_LOAD" or
	"LEAST_CPU_LOAD". The first uses the node with the
	lowest unmber of running Linuxha.net applications,
	whilst the latter uses the node with the lowest 15
	minute load average.
dependencies	This is used to define a comma separated list 
	of applications that should be started prior to the
	application. This information is made use of by the
	\fIclrunapp(1M)\fP and \fIclform(1M)\fP commands.
	This parameter is optional.
autostart	This optional parameter can be set to "true" or
	"false". The default is "false". When set to "true" it
	will indicate that when the \fIclform(1M)\fP command is
	used without the \fB--noapps\fP argument this application
	will be started automatically - along with and 
	applications defined in the dependencies section, if
	present.
.TE

.SH THE NETWORKS SECTION
This section contains information on which, if any, IP addresses are
to be made available when the application is run. This element may
contain 0,1 or more 'networks' element, each of which defines 1 or
more IP addresses that should be made available on that specified 
network.

The configuration of the IP addresses is defined by attributes in
each network element. The 'net' and 'ip' attributes are mandatory,
whilst all other attributes are optional.

.TS
center box expand ;
l l.
Variable	Purpose
_
net	The logical name of the network that is defined
	in the cluster topolgy configuration file - 
	see \fIclconf.xml(5)\fP for details. This is 
	just a single word and must reference an 
	existing network.
ip	The IP address that should be made available when
	this application is running. This IP address should
	be specified in 'dotted-quad' format - for example
	'A.B.C.D'. Multiple IP addresses can be specified
	in various formats. The most obvious one is a comma-
	separated list:

	168.100.1.200,168.100.1.201,168.100.1.202

	A short-hand representation is available if only
	the last octet of the address changes. For example
	it is possible to write the above in the format:

	168.100.1.200,201,202

	Finally if a large number of IP addresses are to be
	specified - and the last octet changes over a 
	consecutive range then a "range" option is available.
	For example the above IP addresse could be written as:

	168.100.1.200-202
netmask	If the default netmask for the IP address to assign
	is not suitable it can be specified as a typical
	4 digit number - i.e. "255.255.0.0". Optional.
broadcast	The broadcast address to assign to the IP
	addresses that are to be configured for the 
	application. This is optional and only necessary if
	the default for the address type is not suitable.
.TE

.SH THE VG SECTION
Typically an application has one volume group associated with it. The
"application" section of the configuration file defines the configuration
of this volume group. 

Actually this entire section is optional - some applications merely
require local storage (for example if they handle replication internally)
and so this section may not be present. Alternatively some environments
make use of multiple volume groups and in this case the complete section
should be duplicated as necessary.

.TS
center box expand ;
l l.
Variable	Purpose
_
name	The name of the volume group that is used for this
	application. This simply needs to the name without
	a path component - such as "vgsg01".
type	This is always "filesystems" currently. Future releases will
	support "raw" for raw logical volume support (often 
	used for databases).
.TE

.SH THE APPLICATION SECTION
This section is important - it defines the scripts to call to start
and stop the application - and how long to wait for such actions
to take place.

Please note that the commands specified below can include arguments
which should be space separated if needed.

.TS
center box expand ;
l l.
Variable	Purpose
_
startscript	The name of the script to run, with any arguments,
	when the application is to be started. Please note that
	the script \fBSHOULD EXIT\fP once the application has
	been started.
stopscript	The script to run to stop the application. This
	should exit when the application has been stopped.
maxstarttime	The maximum amount of time to wait for the startscript
	to complete (in seconds). If the script is not complete
	after this time it will be sent a TERM signal and then a 
	KILL signal. Hence ensure it is long enough!
maxstoptime	This defines the maximum amount of time to wait
	for the application to halt before killing the script and
	forcing the shutdown of the application.
.TE

.SS Suitable Start and Stop Times
The recommendation is to make these times as generous as possible.
If the startime is too short the start-up script will be aborted and
the application start-up will be aborted.

The shutdown time should allow the script several seconds at least
to attempt to stop the application cleanly. If it does not then the
shutdown will kill off any application processes if they are making
use of the file systems associated with the application.

.SH SEE ALSO
.TS
l l.
clbuild(1M)	- Build / Validate cluster topology
cldeamon(1M)	- Cluster status Daemon
clconf.xml(5)	- Cluster configuration file
.TE

.SH AVAILABILITY
This software is freely available from the Linuxha.net website - please see
http://www.linuxha.net for more details.

.SH WARRANTY
This is Open Source Software is per the GNU GPL. It is free to use and
distribute but \fIcomes with no warranty whatsoever\fP. For more information
on the license please see \fBwww.gnu.org/copyleft/gpl.html\fP.

